home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tclx / Handles.man < prev    next >
Encoding:
Text File  |  1991-11-19  |  8.8 KB  |  307 lines
  1. .\"----------------------------------------------------------------------------
  2. .\" The definitions below are for supplemental macros used in Sprite
  3. .\" manual entries.
  4. .\"
  5. .\" .HS name section [date [version]]
  6. .\"    Replacement for .TH in other man pages.  See below for valid
  7. .\"    section names.
  8. .\"
  9. .\" .AP type name in/out [indent]
  10. .\"    Start paragraph describing an argument to a library procedure.
  11. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  12. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  13. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  14. .\"    needed;  use .AS below instead)
  15. .\"
  16. .\" .AS [type [name]]
  17. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  18. .\"    name are examples of largest possible arguments that will be passed
  19. .\"    to .AP later.  If args are omitted, default tab stops are used.
  20. .\"
  21. .\" .BS
  22. .\"    Start box enclosure.  From here until next .BE, everything will be
  23. .\"    enclosed in one large box.
  24. .\"
  25. .\" .BE
  26. .\"    End of box enclosure.
  27. .\"
  28. .\" .VS
  29. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  30. .\"    of man pages.
  31. .\"
  32. .\" .VE
  33. .\"    End of vertical sidebar.
  34. .\"
  35. .\" .DS
  36. .\"    Begin an indented unfilled display.
  37. .\"
  38. .\" .DE
  39. .\"    End of indented unfilled display.
  40. .\"
  41. '    # Heading for Sprite man pages
  42. .de HS
  43. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  44. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  45. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  46. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  47. .if t .wh -1.3i ^B
  48. .nr ^l \\n(.l
  49. .ad b
  50. ..
  51. '    # Start an argument description
  52. .de AP
  53. .ie !"\\$4"" .TP \\$4
  54. .el \{\
  55. .   ie !"\\$2"" .TP \\n()Cu
  56. .   el          .TP 15
  57. .\}
  58. .ie !"\\$3"" \{\
  59. .ta \\n()Au \\n()Bu
  60. \&\\$1    \\fI\\$2\\fP    (\\$3)
  61. .\".b
  62. .\}
  63. .el \{\
  64. .br
  65. .ie !"\\$2"" \{\
  66. \&\\$1    \\fI\\$2\\fP
  67. .\}
  68. .el \{\
  69. \&\\fI\\$1\\fP
  70. .\}
  71. .\}
  72. ..
  73. '    # define tabbing values for .AP
  74. .de AS
  75. .nr )A 10n
  76. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  77. .nr )B \\n()Au+15n
  78. .\"
  79. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  80. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  81. ..
  82. '    # BS - start boxed text
  83. '    # ^y = starting y location
  84. '    # ^b = 1
  85. .de BS
  86. .br
  87. .mk ^y
  88. .nr ^b 1u
  89. .if n .nf
  90. .if n .ti 0
  91. .if n \l'\\n(.lu\(ul'
  92. .if n .fi
  93. ..
  94. '    # BE - end boxed text (draw box now)
  95. .de BE
  96. .nf
  97. .ti 0
  98. .mk ^t
  99. .ie n \l'\\n(^lu\(ul'
  100. .el \{\
  101. .\"    Draw four-sided box normally, but don't draw top of
  102. .\"    box if the box started on an earlier page.
  103. .ie !\\n(^b-1 \{\
  104. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  105. .\}
  106. .el \}\
  107. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  108. .\}
  109. .\}
  110. .fi
  111. .br
  112. .nr ^b 0
  113. ..
  114. '    # VS - start vertical sidebar
  115. '    # ^Y = starting y location
  116. '    # ^v = 1 (for troff;  for nroff this doesn't matter)
  117. .de VS
  118. .mk ^Y
  119. .ie n 'mc \s12\(br\s0
  120. .el .nr ^v 1u
  121. ..
  122. '    # VE - end of vertical sidebar
  123. .de VE
  124. .ie n 'mc
  125. .el \{\
  126. .ev 2
  127. .nf
  128. .ti 0
  129. .mk ^t
  130. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  131. .sp -1
  132. .fi
  133. .ev
  134. .\}
  135. .nr ^v 0
  136. ..
  137. '    # Special macro to handle page bottom:  finish off current
  138. '    # box/sidebar if in box/sidebar mode, then invoked standard
  139. '    # page bottom macro.
  140. .de ^B
  141. .ev 2
  142. 'ti 0
  143. 'nf
  144. .mk ^t
  145. .if \\n(^b \{\
  146. .\"    Draw three-sided box if this is the box's first page,
  147. .\"    draw two sides but no top otherwise.
  148. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  149. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  150. .\}
  151. .if \\n(^v \{\
  152. .nr ^x \\n(^tu+1v-\\n(^Yu
  153. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  154. .\}
  155. .bp
  156. 'fi
  157. .ev
  158. .if \\n(^b \{\
  159. .mk ^y
  160. .nr ^b 2
  161. .\}
  162. .if \\n(^v \{\
  163. .mk ^Y
  164. .\}
  165. ..
  166. '    # DS - begin display
  167. .de DS
  168. .RS
  169. .nf
  170. .sp
  171. ..
  172. '    # DE - end display
  173. .de DE
  174. .fi
  175. .RE
  176. .sp .5
  177. ..
  178. .\"----------------------------------------------------------------------------
  179. .HS Handles tcl
  180. .ad b
  181. .BS
  182. '@index: Tcl_HandleAlloc Tcl_HandleFree Tcl_HandleTblInit Tcl_HandleTblRelease Tcl_HandleTblUseCount Tcl_HandleWalk Tcl_HandleXlate
  183. .SH NAME
  184. Tcl_HandleAlloc, Tcl_HandleFree, Tcl_HandleTblInit,
  185. Tcl_HandleTblRelease, Tcl_HandleTblUseCount Tcl_HandleWalk, 
  186. Tcl_HandleXlate \- Dynamic, handle addressable tables.
  187.  
  188. .SH SYNOPSIS
  189. .nf
  190. \fB#include <tclExtend.h>\fR
  191. .sp
  192. void_pt
  193. \fBTcl_HandleTblInit\fR (\fIhandleBase, entrySize, initEntries\fR)
  194. .sp
  195. int
  196. \fBTcl_HandleTblUseCount\fR (\fIheaderPtr, amount\fR)
  197. .sp
  198. void
  199. \fBTcl_HandleTblRelease\fR (\fIheaderPtr\fR)
  200. .sp
  201. void_pt
  202. \fBTcl_HandleAlloc\fR (\fIheaderPtr, handlePtr\fR)
  203. .sp
  204. void
  205. \fBTcl_HandleFree\fR (\fIheaderPtr, entryPtr\fR)
  206. .sp
  207. void_pt
  208. \fBTcl_HandleWalk\fR (\fIheaderPtr, walkKeyPtr\fR)
  209. .sp
  210. void
  211. \fBTcl_WalkKeyToHandle\fR (\fIheaderPtr, walkKey, handlePtr\fR)
  212. .sp
  213. void_pt
  214. \fBTcl_HandleXlate\fR (\fIinterp, headerPtr, handle\fR)
  215. .SH ARGUMENTS
  216. .AS Tcl_Interp *walkKeyPtr
  217. .AP char *handleBase in
  218. Base name for the handle, numeric entry number will be appended. 
  219. .AP int entrySize in
  220. Size of the table entries, in bytes.
  221. .AP int initEntries in
  222. Initial number of entries to allocate.
  223. .AP int amount in
  224. Amount to alter the use count by.
  225. .AP void_pt headerPtr in
  226. Pointer to the header.
  227. .AP char *handlePtr out
  228. The handle name is returned here.  It must be large enough to hold the handle
  229. base name with a number appended.
  230. .AP Tcl_Interp *interp in
  231. Interpreter to use for error reporting.
  232. .AP char *handle in
  233. Name of handle to operate on.
  234. .AP void_pt entryPtr in
  235. Pointer to a handle table entry.
  236. .AP int *walkKeyPtr i/o
  237. Key used to walk the table, initialize to -1 before the first call.
  238. .AP int walkKey in
  239. Key returned from walking the table.
  240. .BE
  241.  
  242. .SH DESCRIPTION
  243. .PP
  244. The Tcl handle facility provides a way to manage table entries that may be
  245. referenced by a textual handle from Tcl code.  This is provided for 
  246. applications that need to create data structures in one command, return a
  247. reference (i.e. pointer) to that particular data structure and then access
  248. that data structure in other commands. An example application is file handles.
  249. .PP
  250. A handle consists of a base name, which is some unique, meaningful name, such
  251. as `\fBfile\fR' and a numeric value appended to the base name (e.g. `file3').
  252. The handle facility is designed to provide a standard mechanism for building
  253. Tcl commands that allocate and access table entries based on an entry index.
  254. The tables are expanded when needed, consequently pointers to entries should
  255. not be kept, as they will become invalid when the table is expanded.  If the
  256. table entries are large or pointers must be kept to the entries, then the
  257. the entries should be allocated separately and pointers kept in the handle 
  258. table.  A use count is kept on the table.  This use count is intended to
  259. determine when a table shared by multiple commands is to be release.
  260. .PP
  261. \fBTcl_HandleTblInit\fR creates and initialize a Tcl dynamic handle table. 
  262. The specified initial number of entries will be allocated and added to the free
  263. list.  The use count will be set to one.
  264. .PP
  265. \fBTcl_HandleTblUseCount\fR alters the use count on a table and returns the
  266. new value.  The use count has \fIamount\fR added to it, where \fIamount\fR may
  267. be positive, zero or negative.  A zero value retrieves the current use count.
  268. This is normally used to increment the use count when multiple commands are
  269. sharing the table.
  270. .PP
  271. \fBTcl_HandleTblRelease\fR decrements the use count on a table. If it becomes
  272. zero (or negative), the the table will be released. Note that no clean up is
  273. done on the table entry client supplied data.  If clean up must be done, 
  274. then \fBTcl_HandleTblUseCount\fR can be used to decrement the use count.
  275. When it goes to zero, the table may be walked and then released.
  276. \fIHeaderPtr\fR is declared as \fBClientData\fR so that the procedure may
  277. be passed as a command deletion procedure.
  278. .PP
  279. \fBTcl_HandleAlloc\fR allocates an entry and associates a handle with it.
  280. The handle is returned to the buffer pointed to by \fIhandlePtr\fR can then
  281. be used to access the entry.  The buffer must be large enough to accommodate
  282. the base handle name with 2 to 4 digits appended along with a terminating null
  283. byte.
  284. A pointer is returned to the allocated entry.  If \fBTcl_HandleFree\fR
  285. has not been called since initialization, handles will be handed out
  286. sequentially from zero.  This behavior is useful in setting
  287. up initial entries, such as ``\fBstdin\fR'' for a file table.
  288. .PP
  289. \fBTcl_HandleXlate\fR translates a handle to a pointer to the corresponding
  290. table entry.  If the handle is not allocated (open) or is invalid, NULL is
  291. returned and an error message is set in \fIinterp->result\fR.
  292. .PP
  293. \fBTcl_HandleWalk\fR walks through and finds every allocated entry in a table.
  294. Entries may be deallocated during a walk, but should not be allocated.
  295. \fBTcl_HandleWalk\fR
  296. will return a pointer to the entry, or NULL if no more entries are available.
  297. The integer pointed to by \fBwalkKeyPtr\fR should be set to `-1' before the
  298. first call, and then the pointer passed to each subsequent call left 
  299. unmodified.
  300. .PP
  301. \fBTcl_WalkKeyToHandle\fR converts a walk key, as returned from a call to
  302. \fBTcl_HandleWalk\fR into a handle.
  303. .PP
  304. \fBTcl_HandleFree\fR frees a handle table entry.
  305. .SH KEYWORDS
  306. handle, table, allocate
  307.